Skip to content

chore: add SEP-2640 requirement-traceability YAML (Skills Extension)#330

Draft
panyam wants to merge 8 commits into
modelcontextprotocol:mainfrom
panyam:chore/sep-2640-yaml
Draft

chore: add SEP-2640 requirement-traceability YAML (Skills Extension)#330
panyam wants to merge 8 commits into
modelcontextprotocol:mainfrom
panyam:chore/sep-2640-yaml

Conversation

@panyam

@panyam panyam commented Jun 4, 2026

Copy link
Copy Markdown

Adds src/seps/sep-2640.yaml, the requirement-traceability file for the Skills Extension
SEP. Floats the requirement model out for Skills Over MCP Working Group review ahead of
scenario implementation. No scenarios in this PR.

Motivation and Context

SEP-2640 introduces a skill:// resource convention for serving Agent Skills over MCP. As
an Extensions Track SEP, it needs conformance coverage before review under SEP-2133. Landing
the requirement extraction first lets the Skills Over MCP Working Group sanity-check which
normative obligations the harness will assert versus which are excluded as host-internal
policy or UI affordances, before any scenario design starts.

The yaml also carries a leading provenance comment (spec_source commit ref +
extracted_at date) so future SEP drift is detectable from the file alone, without
rebuilding the extraction.

How Has This Been Tested?

No runtime behavior in this change. Validation performed:

  • YAML parses cleanly. 25 check: rows + 8 excluded: rows (33 total).
  • Lefthook pre-push (Test, Code Formatting) passes on each commit.
  • All RFC 2119 sentences from the SEP's normative sections (Specification + Security
    Implications) are accounted for. MAY / OPTIONAL sentences are intentionally dropped per
    the conformance-repo convention.

End-to-end conformance against the reference SDK will follow in a later PR once scenarios
exist.

Breaking Changes

None. The file is additive metadata. Existing SEP yamls, scenarios, and the traceability
manifest are untouched. traceability.json will pick up the new check IDs the next time it
is regenerated against a suite run.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

Two requirement merges to flag for reviewers:

  • host-no-unverified-content (MUST NOT) is folded into host-verify-digest. They state
    the same obligation as positive and negative; one row keeps both halves linked.
  • host-archive-safety collapses the Discovery-section and Security-Implications
    restatements of the archive-safety rule into a single row.

Excluded categories and reasoning:

  • Host-internal policy (untrusted-input handling, no implicit execution, context-authority
    ordering).
  • UI affordances (origin indicator, inspect-before-load, template discovery).
  • Sub-MCP behavior (DNS resolution of the URI authority component, archive-format detection
    logic between mimeType and URL suffix).

Planned followups (separate PRs):

  • Scenarios under src/scenarios/{server,client}/skills.ts, registered in
    src/scenarios/index.ts.
  • Reference implementation in at least one SDK, exercising those scenarios end-to-end
    against the everything-server / everything-client.
  • Passing and negative cases added to the everything-server per AGENTS.md.

panyam added 8 commits June 3, 2026 17:17
…rce-template)

Re-extract sep-2640.yaml against current SEP-2640 HEAD. The SEP removed
the `mcp-resource-template` index entry type in two commits on
2026-06-04 (fd50cc91 "Remove mcp-resource-template entries from skill
index", 556154c0 "Remove remaining resource template mentions from SDK
and rationale sections"), after this extraction was first captured on
2026-06-03 at b77fdfe8. Provenance comment bumped accordingly.

Resulting changes:

- sep-2640-index-entry-type-enum: drop `"mcp-resource-template"` from
  the enum.
- sep-2640-index-name-required: drop the "is Required for ... Omitted
  for mcp-resource-template" conditional language; the column is now
  unconditional Required=Yes at SEP HEAD.
- sep-2640-index-digest-required: same simplification; also align
  "hexadecimal" -> "hex" with the HEAD table text.
- sep-2640-template-resource-template-registered: removed. The SEP no
  longer defines a template entry type, so the SHOULD on registering an
  MCP resource template is gone.
- Excluded "Hosts SHOULD surface template entries..." excerpt: removed.
  The sentence no longer exists in the SEP.

Sweep verified: zero "template" mentions in the SEP at HEAD. Security
Implications section sentences referenced by the remaining excluded
entries are intact. No other check rows touched.
…y/read

Adds the conformance scenario for the SEP-2640 directoryRead surface that
landed in spec commit 2e04c48d (2026-06-09). Per AGENTS.md "fewer scenarios,
more checks", a single ResourcesDirectoryReadScenario emits 6
ConformanceChecks, one per new sep-2640.yaml requirement row.

Class named for the wire method (resources/directory/read), matching the
existing ResourcesListScenario / ResourcesReadTextScenario / etc. family in
src/scenarios/server/resources.ts. The runner-facing name field stays as
'sep-2640-skills' (umbrella) so mcpkit's conformance/Makefile entry
--scenario sep-2640-skills keeps working without a cross-repo race.

src/seps/sep-2640.yaml
- File-level provenance held at 556154c (the existing PR 330 baseline).
- 6 new check rows appended for the directoryRead additions, each
  carrying a verbatim, grep-F-searchable excerpt from the SEP at
  2e04c48da90224000e750ffd54a3611f2824fbc0:
    - sep-2640-capability-directory-read-flag
    - sep-2640-directory-read-method-registered
    - sep-2640-directory-read-subdir-mimetype
    - sep-2640-directory-read-result-resources-shape
    - sep-2640-directory-read-invalid-params
    - sep-2640-directory-read-pagination
- forward_reference header comment notes the asymmetry: PR 97 schema
  rewrite (360123d0, 2026-06-08) made 3 existing rows stale and drifted
  ~11 others' wording; full re-extraction at SEP HEAD is mcpkit#780's
  lifecycle. Provenance deliberately holds at 556154c until that lands.

src/types.ts
- Adds io.modelcontextprotocol/skills to EXTENSION_IDS so the scenario's
  source: { extensionId: ... } tag type-checks.

src/scenarios/server/directory.ts (new)
- Capability discovery via wire-observable signal: -32601 method-not-found
  is the only definitive "server did not declare directoryRead" signal.
- Fixture assumption: server exposes skill://acme/billing/refunds/templates
  with at least one subdirectory child (mcpkit examples/skills layout).
  No skill:// resources at all -> every check emits SKIPPED so the
  scenario stays green against upstream's everything-server fixture.
- 6 checks (1:1 with the YAML rows above):
  1. directoryRead declared (derived from method registration)
  2. method registered (happy-path call succeeds)
  3. result.resources shape matches resources/list
  4. subdir child carries mimeType: "inode/directory"
  5. non-directory URI returns -32602
  6. nextCursor round-trips (single-page is conformant)

src/scenarios/index.ts
- Imports + registers ResourcesDirectoryReadScenario in
  allClientScenariosList, matching the registration name 'sep-2640-skills'
  that mcpkit's conformance/Makefile already passes to --scenario.

Verified end-to-end against mcpkit examples/skills:
  cd ~/newstack/mcpkit/main && \
    MCPCONFORMANCE_SKILLS_PATH=~/newstack/mcpkit/conf-skills \
    make -C conformance testconf-skills
  -> 6/6 SUCCESS, 0 failed, 0 warnings.

Out of scope:
- PR 97 schema rewrite YAML refresh (separate ticket, mcpkit#780 lifecycle).
- Negative-capability fixture (server without directoryRead) - mcpkit
  examples/skills has no flag for it; ext/skills/client_directory_test.go
  already covers the SDK pre-call guard.
feat(sep-2640): ResourcesDirectoryReadScenario for resources/directory/read (mcpkit#784)
@panyam panyam marked this pull request as ready for review June 16, 2026 21:34
@panyam panyam marked this pull request as draft June 16, 2026 21:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant